home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / lwres / lwres.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-09-17  |  15.6 KB  |  580 lines
  1. /*
  2.  * Copyright (C) 2004, 2005  Internet Systems Consortium, Inc. ("ISC")
  3.  * Copyright (C) 2000, 2001  Internet Software Consortium.
  4.  *
  5.  * Permission to use, copy, modify, and distribute this software for any
  6.  * purpose with or without fee is hereby granted, provided that the above
  7.  * copyright notice and this permission notice appear in all copies.
  8.  *
  9.  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10.  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11.  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12.  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13.  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14.  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15.  * PERFORMANCE OF THIS SOFTWARE.
  16.  */
  17.  
  18. /* $Id: lwres.h,v 1.51.18.2 2005/04/29 00:17:22 marka Exp $ */
  19.  
  20. #ifndef LWRES_LWRES_H
  21. #define LWRES_LWRES_H 1
  22.  
  23. #include <stdio.h>
  24.  
  25. #include <lwres/context.h>
  26. #include <lwres/lang.h>
  27. #include <lwres/list.h>
  28. #include <lwres/lwpacket.h>
  29. #include <lwres/platform.h>
  30.  
  31. /*! \file */
  32.  
  33. /*!
  34.  * Design notes:
  35.  *
  36.  * Each opcode has two structures and three functions which operate on each
  37.  * structure.  For example, using the "no operation/ping" opcode as an
  38.  * example:
  39.  *
  40.  *    <ul><li>lwres_nooprequest_t:
  41.  *
  42.  *        lwres_nooprequest_render() takes a lwres_nooprequest_t and
  43.  *        and renders it into wire format, storing the allocated
  44.  *        buffer information in a passed-in buffer.  When this buffer
  45.  *        is no longer needed, it must be freed by
  46.  *        lwres_context_freemem().  All other memory used by the
  47.  *        caller must be freed manually, including the
  48.  *        lwres_nooprequest_t passed in.<br /><br />
  49.  *
  50.  *        lwres_nooprequest_parse() takes a wire format message and
  51.  *        breaks it out into a lwres_nooprequest_t.  The structure
  52.  *        must be freed via lwres_nooprequest_free() when it is no longer
  53.  *        needed.<br /><br />
  54.  *
  55.  *        lwres_nooprequest_free() releases into the lwres_context_t
  56.  *        any space allocated during parsing.</li>
  57.  *
  58.  *    <li>lwres_noopresponse_t:
  59.  *
  60.  *        The functions used are similar to the three used for
  61.  *        requests, just with different names.</li></ul>
  62.  *
  63.  * Typically, the client will use request_render, response_parse, and
  64.  * response_free, while the daemon will use request_parse, response_render,
  65.  * and request_free.
  66.  *
  67.  * The basic flow of a typical client is:
  68.  *
  69.  *    \li fill in a request_t, and call the render function.
  70.  *
  71.  *    \li Transmit the buffer returned to the daemon.
  72.  *
  73.  *    \li Wait for a response.
  74.  *
  75.  *    \li When a response is received, parse it into a response_t.
  76.  *
  77.  *    \li free the request buffer using lwres_context_freemem().
  78.  *
  79.  *    \li free the response structure and its associated buffer using
  80.  *    response_free().
  81.  */
  82.  
  83. #define LWRES_UDP_PORT        921    /*%< UDP Port Number */
  84. #define LWRES_RECVLENGTH    16384 /*%< Maximum Packet Length */
  85. #define LWRES_ADDR_MAXLEN    16    /*%< changing this breaks ABI */
  86. #define LWRES_RESOLV_CONF    "/etc/resolv.conf" /*%< Location of resolv.conf */
  87.  
  88. /*% DNSSEC is not required (input).  Only relevant to rrset queries. */
  89. #define LWRES_FLAG_TRUSTNOTREQUIRED    0x00000001U
  90. /*% The data was crypto-verified with DNSSEC (output). */
  91. #define LWRES_FLAG_SECUREDATA        0x00000002U
  92.  
  93. /*% no-op */
  94. #define LWRES_OPCODE_NOOP        0x00000000U
  95.  
  96. /*% lwres_nooprequest_t */
  97. typedef struct {
  98.     /* public */
  99.     lwres_uint16_t            datalength;
  100.     unsigned char               *data;
  101. } lwres_nooprequest_t;
  102.  
  103. /*% lwres_noopresponse_t */
  104. typedef struct {
  105.     /* public */
  106.     lwres_uint16_t            datalength;
  107.     unsigned char               *data;
  108. } lwres_noopresponse_t;
  109.  
  110. /*% get addresses by name */
  111. #define LWRES_OPCODE_GETADDRSBYNAME    0x00010001U
  112.  
  113. /*% lwres_addr_t */
  114. typedef struct lwres_addr lwres_addr_t;
  115.  
  116. /*% LWRES_LIST */
  117. typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
  118.  
  119. /*% lwres_addr */
  120. struct lwres_addr {
  121.     lwres_uint32_t            family;
  122.     lwres_uint16_t            length;
  123.     unsigned char            address[LWRES_ADDR_MAXLEN];
  124.     LWRES_LINK(lwres_addr_t)    link;
  125. };
  126.  
  127. /*% lwres_gabnrequest_t */
  128. typedef struct {
  129.     /* public */
  130.     lwres_uint32_t            flags;
  131.     lwres_uint32_t            addrtypes;
  132.     lwres_uint16_t            namelen;
  133.     char                   *name;
  134. } lwres_gabnrequest_t;
  135.  
  136. /*% lwres_gabnresponse_t */
  137. typedef struct {
  138.     /* public */
  139.     lwres_uint32_t            flags;
  140.     lwres_uint16_t            naliases;
  141.     lwres_uint16_t            naddrs;
  142.     char                   *realname;
  143.     char                  **aliases;
  144.     lwres_uint16_t            realnamelen;
  145.     lwres_uint16_t               *aliaslen;
  146.     lwres_addrlist_t        addrs;
  147.     /*! if base != NULL, it will be freed when this structure is freed. */
  148.     void                   *base;
  149.     size_t                baselen;
  150. } lwres_gabnresponse_t;
  151.  
  152. /*% get name by address */
  153. #define LWRES_OPCODE_GETNAMEBYADDR    0x00010002U
  154.  
  155. /*% lwres_gnbarequest_t */
  156. typedef struct {
  157.     /* public */
  158.     lwres_uint32_t            flags;
  159.     lwres_addr_t            addr;
  160. } lwres_gnbarequest_t;
  161.  
  162. /*% lwres_gnbaresponse_t */
  163. typedef struct {
  164.     /* public */
  165.     lwres_uint32_t            flags;
  166.     lwres_uint16_t            naliases;
  167.     char                   *realname;
  168.     char                  **aliases;
  169.     lwres_uint16_t            realnamelen;
  170.     lwres_uint16_t               *aliaslen;
  171.     /*! if base != NULL, it will be freed when this structure is freed. */
  172.     void                   *base;
  173.     size_t                baselen;
  174. } lwres_gnbaresponse_t;
  175.  
  176. /*% get rdata by name */
  177. #define LWRES_OPCODE_GETRDATABYNAME    0x00010003U
  178.  
  179. /*% lwres_grbnrequest_t */
  180. typedef struct {
  181.     /* public */
  182.     lwres_uint32_t            flags;
  183.     lwres_uint16_t            rdclass;
  184.     lwres_uint16_t            rdtype;
  185.     lwres_uint16_t            namelen;
  186.     char                   *name;
  187. } lwres_grbnrequest_t;
  188.  
  189. /*% lwres_grbnresponse_t */
  190. typedef struct {
  191.     /* public */
  192.     lwres_uint32_t            flags;
  193.     lwres_uint16_t            rdclass;
  194.     lwres_uint16_t            rdtype;
  195.     lwres_uint32_t            ttl;
  196.     lwres_uint16_t            nrdatas;
  197.     lwres_uint16_t            nsigs;
  198.     char                   *realname;
  199.     lwres_uint16_t            realnamelen;
  200.     unsigned char              **rdatas;
  201.     lwres_uint16_t               *rdatalen;
  202.     unsigned char              **sigs;
  203.     lwres_uint16_t               *siglen;
  204.     /*% if base != NULL, it will be freed when this structure is freed. */
  205.     void                   *base;
  206.     size_t                baselen;
  207. } lwres_grbnresponse_t;
  208.  
  209. /*% Used by lwres_getrrsetbyname() */
  210. #define LWRDATA_VALIDATED    0x00000001
  211.  
  212. /*!
  213.  * resolv.conf data
  214.  */
  215.  
  216. #define LWRES_CONFMAXNAMESERVERS 3    /*%< max 3 "nameserver" entries */
  217. #define LWRES_CONFMAXLWSERVERS 1    /*%< max 1 "lwserver" entry */
  218. #define LWRES_CONFMAXSEARCH 8        /*%< max 8 domains in "search" entry */
  219. #define LWRES_CONFMAXLINELEN 256    /*%< max size of a line */
  220. #define LWRES_CONFMAXSORTLIST 10    /*%< max 10 */
  221.  
  222. /*% lwres_conf_t */
  223. typedef struct {
  224.     lwres_context_t *lwctx;
  225.     lwres_addr_t    nameservers[LWRES_CONFMAXNAMESERVERS];
  226.     lwres_uint8_t    nsnext;        /*%< index for next free slot */
  227.  
  228.     lwres_addr_t    lwservers[LWRES_CONFMAXLWSERVERS];
  229.     lwres_uint8_t    lwnext;        /*%< index for next free slot */
  230.  
  231.     char           *domainname;
  232.  
  233.     char            *search[LWRES_CONFMAXSEARCH];
  234.     lwres_uint8_t    searchnxt;    /*%< index for next free slot */
  235.  
  236.     struct {
  237.         lwres_addr_t addr;
  238.         /*% mask has a non-zero 'family' and 'length' if set */
  239.         lwres_addr_t mask;
  240.     } sortlist[LWRES_CONFMAXSORTLIST];
  241.     lwres_uint8_t    sortlistnxt;
  242.  
  243.     lwres_uint8_t    resdebug;      /*%< non-zero if 'options debug' set */
  244.     lwres_uint8_t    ndots;           /*%< set to n in 'options ndots:n' */
  245.     lwres_uint8_t    no_tld_query;  /*%< non-zero if 'options no_tld_query' */
  246. } lwres_conf_t;
  247.  
  248. #define LWRES_ADDRTYPE_V4        0x00000001U    /*%< ipv4 */
  249. #define LWRES_ADDRTYPE_V6        0x00000002U    /*%< ipv6 */
  250.  
  251. #define LWRES_MAX_ALIASES        16        /*%< max # of aliases */
  252. #define LWRES_MAX_ADDRS            64        /*%< max # of addrs */
  253.  
  254. LWRES_LANG_BEGINDECLS
  255.  
  256. /*% This is in host byte order. */
  257. LIBLWRES_EXTERNAL_DATA extern lwres_uint16_t lwres_udp_port;
  258.  
  259. LIBLWRES_EXTERNAL_DATA extern const char *lwres_resolv_conf;
  260.  
  261. lwres_result_t
  262. lwres_gabnrequest_render(lwres_context_t *ctx, lwres_gabnrequest_t *req,
  263.              lwres_lwpacket_t *pkt, lwres_buffer_t *b);
  264.  
  265. lwres_result_t
  266. lwres_gabnresponse_render(lwres_context_t *ctx, lwres_gabnresponse_t *req,
  267.               lwres_lwpacket_t *pkt, lwres_buffer_t *b);
  268.  
  269. lwres_result_t
  270. lwres_gabnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b,
  271.             lwres_lwpacket_t *pkt, lwres_gabnrequest_t **structp);
  272.  
  273. lwres_result_t
  274. lwres_gabnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b,
  275.              lwres_lwpacket_t *pkt,
  276.              lwres_gabnresponse_t **structp);
  277.  
  278. void
  279. lwres_gabnrequest_free(lwres_context_t *ctx, lwres_gabnrequest_t **structp);
  280. /**<
  281.  * Frees any dynamically allocated memory for this structure.
  282.  *
  283.  * Requires:
  284.  *
  285.  *    ctx != NULL, and be a context returned via lwres_context_create().
  286.  *
  287.  *    structp != NULL && *structp != NULL.
  288.  *
  289.  * Ensures:
  290.  *
  291.  *    *structp == NULL.
  292.  *
  293.  *    All memory allocated by this structure will be returned to the
  294.  *    system via the context's free function.
  295.  */
  296.  
  297. void
  298. lwres_gabnresponse_free(lwres_context_t *ctx, lwres_gabnresponse_t **structp);
  299. /**<
  300.  * Frees any dynamically allocated memory for this structure.
  301.  *
  302.  * Requires:
  303.  *
  304.  *    ctx != NULL, and be a context returned via lwres_context_create().
  305.  *
  306.  *    structp != NULL && *structp != NULL.
  307.  *
  308.  * Ensures:
  309.  *
  310.  *    *structp == NULL.
  311.  *
  312.  *    All memory allocated by this structure will be returned to the
  313.  *    system via the context's free function.
  314.  */
  315.  
  316.  
  317. lwres_result_t
  318. lwres_gnbarequest_render(lwres_context_t *ctx, lwres_gnbarequest_t *req,
  319.              lwres_lwpacket_t *pkt, lwres_buffer_t *b);
  320.  
  321. lwres_result_t
  322. lwres_gnbaresponse_render(lwres_context_t *ctx, lwres_gnbaresponse_t *req,
  323.               lwres_lwpacket_t *pkt, lwres_buffer_t *b);
  324.  
  325. lwres_result_t
  326. lwres_gnbarequest_parse(lwres_context_t *ctx, lwres_buffer_t *b,
  327.             lwres_lwpacket_t *pkt, lwres_gnbarequest_t **structp);
  328.  
  329. lwres_result_t
  330. lwres_gnbaresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b,
  331.              lwres_lwpacket_t *pkt,
  332.              lwres_gnbaresponse_t **structp);
  333.  
  334. void
  335. lwres_gnbarequest_free(lwres_context_t *ctx, lwres_gnbarequest_t **structp);
  336. /**<
  337.  * Frees any dynamically allocated memory for this structure.
  338.  *
  339.  * Requires:
  340.  *
  341.  *    ctx != NULL, and be a context returned via lwres_context_create().
  342.  *
  343.  *    structp != NULL && *structp != NULL.
  344.  *
  345.  * Ensures:
  346.  *
  347.  *    *structp == NULL.
  348.  *
  349.  *    All memory allocated by this structure will be returned to the
  350.  *    system via the context's free function.
  351.  */
  352.  
  353. void
  354. lwres_gnbaresponse_free(lwres_context_t *ctx, lwres_gnbaresponse_t **structp);
  355. /**<
  356.  * Frees any dynamically allocated memory for this structure.
  357.  *
  358.  * Requires:
  359.  *
  360.  *    ctx != NULL, and be a context returned via lwres_context_create().
  361.  *
  362.  *    structp != NULL && *structp != NULL.
  363.  *
  364.  * Ensures:
  365.  *
  366.  *    *structp == NULL.
  367.  *
  368.  *    All memory allocated by this structure will be returned to the
  369.  *    system via the context's free function.
  370.  */
  371.  
  372. lwres_result_t
  373. lwres_grbnrequest_render(lwres_context_t *ctx, lwres_grbnrequest_t *req,
  374.              lwres_lwpacket_t *pkt, lwres_buffer_t *b);
  375.  
  376. lwres_result_t
  377. lwres_grbnresponse_render(lwres_context_t *ctx, lwres_grbnresponse_t *req,
  378.               lwres_lwpacket_t *pkt, lwres_buffer_t *b);
  379.  
  380. lwres_result_t
  381. lwres_grbnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b,
  382.             lwres_lwpacket_t *pkt, lwres_grbnrequest_t **structp);
  383.  
  384. lwres_result_t
  385. lwres_grbnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b,
  386.              lwres_lwpacket_t *pkt,
  387.              lwres_grbnresponse_t **structp);
  388.  
  389. void
  390. lwres_grbnrequest_free(lwres_context_t *ctx, lwres_grbnrequest_t **structp);
  391. /**<
  392.  * Frees any dynamically allocated memory for this structure.
  393.  *
  394.  * Requires:
  395.  *
  396.  *    ctx != NULL, and be a context returned via lwres_context_create().
  397.  *
  398.  *    structp != NULL && *structp != NULL.
  399.  *
  400.  * Ensures:
  401.  *
  402.  *    *structp == NULL.
  403.  *
  404.  *    All memory allocated by this structure will be returned to the
  405.  *    system via the context's free function.
  406.  */
  407.  
  408. void
  409. lwres_grbnresponse_free(lwres_context_t *ctx, lwres_grbnresponse_t **structp);
  410. /**<
  411.  * Frees any dynamically allocated memory for this structure.
  412.  *
  413.  * Requires:
  414.  *
  415.  *    ctx != NULL, and be a context returned via lwres_context_create().
  416.  *
  417.  *    structp != NULL && *structp != NULL.
  418.  *
  419.  * Ensures:
  420.  *
  421.  *    *structp == NULL.
  422.  *
  423.  *    All memory allocated by this structure will be returned to the
  424.  *    system via the context's free function.
  425.  */
  426.  
  427. lwres_result_t
  428. lwres_nooprequest_render(lwres_context_t *ctx, lwres_nooprequest_t *req,
  429.              lwres_lwpacket_t *pkt, lwres_buffer_t *b);
  430. /**<
  431.  * Allocate space and render into wire format a noop request packet.
  432.  *
  433.  * Requires:
  434.  *
  435.  *    ctx != NULL, and be a context returned via lwres_context_create().
  436.  *
  437.  *    b != NULL, and points to a lwres_buffer_t.  The contents of the
  438.  *    buffer structure will be initialized to contain the wire-format
  439.  *    noop request packet.
  440.  *
  441.  *    Caller needs to fill in parts of "pkt" before calling:
  442.  *        serial, maxrecv, result.
  443.  *
  444.  * Returns:
  445.  *
  446.  *    Returns 0 on success, non-zero on failure.
  447.  *
  448.  *    On successful return, *b will contain data about the wire-format
  449.  *    packet.  It can be transmitted in any way, including lwres_sendblock().
  450.  */
  451.  
  452. lwres_result_t
  453. lwres_noopresponse_render(lwres_context_t *ctx, lwres_noopresponse_t *req,
  454.               lwres_lwpacket_t *pkt, lwres_buffer_t *b);
  455.  
  456. lwres_result_t
  457. lwres_nooprequest_parse(lwres_context_t *ctx, lwres_buffer_t *b,
  458.             lwres_lwpacket_t *pkt, lwres_nooprequest_t **structp);
  459. /**<
  460.  * Parse a noop request.  Note that to get here, the lwpacket must have
  461.  * already been parsed and removed by the caller, otherwise it would be
  462.  * pretty hard for it to know this is the right function to call.
  463.  *
  464.  * The function verifies bits of the header, but does not modify it.
  465.  */
  466.  
  467. lwres_result_t
  468. lwres_noopresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b,
  469.              lwres_lwpacket_t *pkt,
  470.              lwres_noopresponse_t **structp);
  471.  
  472. void
  473. lwres_nooprequest_free(lwres_context_t *ctx, lwres_nooprequest_t **structp);
  474.  
  475. void
  476. lwres_noopresponse_free(lwres_context_t *ctx, lwres_noopresponse_t **structp);
  477.  
  478. /**<
  479.  * Frees any dynamically allocated memory for this structure.
  480.  *
  481.  * Requires:
  482.  *
  483.  *    ctx != NULL, and be a context returned via lwres_context_create().
  484.  *
  485.  *    structp != NULL && *structp != NULL.
  486.  *
  487.  * Ensures:
  488.  *
  489.  *    *structp == NULL.
  490.  *
  491.  *    All memory allocated by this structure will be returned to the
  492.  *    system via the context's free function.
  493.  */
  494.  
  495. lwres_result_t
  496. lwres_conf_parse(lwres_context_t *ctx, const char *filename);
  497. /**<
  498.  * parses a resolv.conf-format file and stores the results in the structure
  499.  * pointed to by *ctx.
  500.  *
  501.  * Requires:
  502.  *    ctx != NULL
  503.  *    filename != NULL && strlen(filename) > 0
  504.  *
  505.  * Returns:
  506.  *    LWRES_R_SUCCESS on a successful parse.
  507.  *    Anything else on error, although the structure may be partially filled
  508.  *    in.
  509.  */
  510.  
  511. lwres_result_t
  512. lwres_conf_print(lwres_context_t *ctx, FILE *fp);
  513. /**<
  514.  * Prints a resolv.conf-format of confdata output to fp.
  515.  *
  516.  * Requires:
  517.  *    ctx != NULL
  518.  */
  519.  
  520. void
  521. lwres_conf_init(lwres_context_t *ctx);
  522. /**<
  523.  * sets all internal fields to a default state. Used to initialize a new
  524.  * lwres_conf_t structure (not reset a used on).
  525.  *
  526.  * Requires:
  527.  *    ctx != NULL
  528.  */
  529.  
  530. void
  531. lwres_conf_clear(lwres_context_t *ctx);
  532. /**<
  533.  * frees all internally allocated memory in confdata. Uses the memory
  534.  * routines supplied by ctx.
  535.  *
  536.  * Requires:
  537.  *    ctx != NULL
  538.  */
  539.  
  540. lwres_conf_t *
  541. lwres_conf_get(lwres_context_t *ctx);
  542. /**<
  543.  * Be extremely cautions in modifying the contents of this structure; it
  544.  * needs an API to return the various bits of data, walk lists, etc.
  545.  *
  546.  * Requires:
  547.  *    ctx != NULL
  548.  */
  549.  
  550. /*
  551.  * Helper functions
  552.  */
  553.  
  554. lwres_result_t
  555. lwres_data_parse(lwres_buffer_t *b, unsigned char **p, lwres_uint16_t *len);
  556.  
  557. lwres_result_t
  558. lwres_string_parse(lwres_buffer_t *b, char **c, lwres_uint16_t *len);
  559.  
  560. lwres_result_t
  561. lwres_addr_parse(lwres_buffer_t *b, lwres_addr_t *addr);
  562.  
  563. lwres_result_t
  564. lwres_getaddrsbyname(lwres_context_t *ctx, const char *name,
  565.              lwres_uint32_t addrtypes, lwres_gabnresponse_t **structp);
  566.  
  567. lwres_result_t
  568. lwres_getnamebyaddr(lwres_context_t *ctx, lwres_uint32_t addrtype,
  569.             lwres_uint16_t addrlen, const unsigned char *addr,
  570.             lwres_gnbaresponse_t **structp);
  571.  
  572. lwres_result_t
  573. lwres_getrdatabyname(lwres_context_t *ctx, const char *name,
  574.              lwres_uint16_t rdclass, lwres_uint16_t rdtype,
  575.              lwres_uint32_t flags, lwres_grbnresponse_t **structp);
  576.  
  577. LWRES_LANG_ENDDECLS
  578.  
  579. #endif /* LWRES_LWRES_H */
  580.